/**
 * @addtogroup mem_alloc
 * mem_alloc
 * @{
 */
/**
 * @file        mem_alloc.h
 * @brief       XXXX
 * @note        XXXX
 * @author      靳普诏(puzhao.jin@hopechart.com)
 * @date        2025/09/17
 * @version     1.0

 * @par         修改日志
 * <table>
 * <tr><th>Date         <th>Version     <th>Author      <th> Description
 * <tr><td>2025/09/17   <td>1.0         <td>靳普诏       <td> 创建初始版本
 * @copyright 杭州鸿泉物联网技术股份有限公司
 */

#ifndef _MEM_ALLOC_H_
#define _MEM_ALLOC_H_

#include "az_clib/BaseTypes.h"

#ifdef __cplusplus
extern "C"
{
#endif


/**
 * @brief       初始化内存分配器
 * @param[in]   buff  用于内存分配的缓冲区指针
 * @param[in]   size  缓冲区大小（字节数）
 * @return      Bool  初始化结果
 * @retval      True  初始化成功
 * @retval      False 初始化失败（参数无效或已初始化）
 * @note        必须在使用其他内存分配函数前调用此函数
 * @warning     buff指向的内存区域在分配器生命周期内不能被释放
 */
Bool AzMemAllocInit(void *buff, Int32 size);

/**
 * @brief       反初始化内存分配器
 * @return      Bool  反初始化结果
 * @retval      True  反初始化成功
 * @retval      False 反初始化失败（未初始化或仍有内存未释放）
 * @note        调用后将释放所有分配的内存，使分配器回到未初始化状态
 * @warning     确保所有分配的内存都已正确释放后再调用此函数
 */
Bool AzMemAllocDone(void);

/**
 * @brief       分配指定大小的内存块
 * @param[in]   size  要分配的内存大小（字节数）
 * @return      void* 分配的内存块指针
 * @retval      非NULL 分配成功，返回内存块起始地址
 * @retval      NULL   分配失败（内存不足、未初始化或参数无效）
 * @note        分配的内存内容未初始化，使用前需要设置初值
 * @warning     分配的内存必须通过AzMemFree释放，避免内存泄漏
 */
void *AzMemAlloc(Int32 size);

/**
 * @brief       释放指定的内存块
 * @param[in]   ptr   要释放的内存块指针
 * @return      void  无返回值
 * @note        ptr必须是通过AzMemAlloc或AzMemRealloc分配的有效指针
 * @warning     释放后不要再访问该内存区域，避免野指针错误
 * @warning     对同一指针多次调用释放或释放无效指针将导致未定义行为
 */
void  AzMemFree(void *ptr);

/**
 * @brief       重新分配内存块大小
 * @param[in]   ptr   原内存块指针（可以为NULL）
 * @param[in]   size  新的内存大小（字节数）
 * @return      void* 重新分配的内存块指针
 * @retval      非NULL 重新分配成功，返回新内存块起始地址
 * @retval      NULL   重新分配失败（内存不足、未初始化或参数无效）
 * @note        如果ptr为NULL，行为等同于AzMemAlloc(size)
 * @note        如果size为0，行为等同于AzMemFree(ptr)并返回NULL
 * @note        原内存内容在新大小范围内会被保留
 * @warning     返回的指针可能与原指针不同，必须使用新返回的指针
 * @warning     如果重新分配失败，原内存块保持不变且仍然有效
 */
void *AzMemRealloc(void *ptr, Int32 size);




#ifdef __cplusplus
}  ///< extern "C"
#endif

#endif  ///< _MEM_ALLOC_H_

/**
 * @}  Generated on "2025-09-17 22:28:49" by the tool "gen_hq_file.py >> V20231119" 
 */

